Shareware Grab Bag

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Grab Bag / Shareware Grab Bag.iso / 001 / popt.arc / P-OPT.DOC next >

Wrap

Text File | 1987-04-29 | 17.6 KB | 410 lines

P - OPT v. 1.0 " Power Tools for Power Users " By Gizmo Mike (C) InfoSoft, 1987 The Information booth (316) 684 8744 1.0 Introduction P - OPT is a PROCOMM command file optimizer and a whole lot more! What it will do for you is read a PROCOMM command file and optimize it for speed at runtime. As procomm executes a command file, it reads every single byte much as an interpeter would. While using the 4 letter abbreviations would speed up execution, it makes lengthy source code harder to read and modify. P-OPT will allow you to comment liberally in the original command file, then optimize it for speed. This leaves you with 2 "versions" one with comments and such for future modifications, and another streamlined for fast, Fast, FAST, FASTEST execution at runtime. Basically, when run, P-OPT will read the specified command file, then optimize it by removing any lines that are totally remarks, strip remarks from other lines, strip trailing and leading spaces (ie it undoes indentation) then substitutes the short for for the commmand key word (MESSAGE becomes MESS, TRANSMIT becomes TRANS etc). 1.1 Execution Time Granted, this is not for your average 5 line command file, but for larger intricate command files, it can help out a bunch. VERSA, a PC Pursuit navigator, in its commented form is 915 lines, 36K. Once run thru P-OPT, is shrinks to a lean and mean 658 lines, 10.7K. And it is fast! On an AT the process takes 23 secs, on a PC a mere 72 secs! 1.2 Basic P-OPT functions Functions supported in P-OPT, mainly thru the use of meta commands: * Optimize PROCOMM scripts for optimimum run time. - Remove leading space from quoted strings. - Substitute 4 character form of all, most or some PROCOMM command words. - Truncate labels to the first 8 characters and a ":". - Truncate label references (GOTO LONGLABEL) to first 8 characters. - Remove blank lines from source. - Strip trailing spaces and remarks from source. * Produce printed output directly from P-OPT * Allow for remarks of special significance to remain in the optimized output. * Assign text strings via meta-commands to title and label the output. * Produce a crossreference, of optimized code, with a SOURCE line number. 2.0 Command line syntax A few parameters are passed to P-OPT from the command line. P-OPT's command line arguments ARE POSITIONAL! Syntax: P-OPT source[.CMD] target[.OPT] [/c | /nc ] 2.1 Command line parameters The first parameter passed tells P-OPT what source file to optimize. You can enter the extension of .CMD or not, but P-OPT will look for source.CMD. If it does not exist it will tell you. The second parameter is the output file name. Here, you can enter the extension of .OPT or not, but P-OPT will output to target.OPT. If the file exists, P-OPY will ask you if you are sure that you want to overwrite it. If you do not, if will prompt you for a new filename. If you wish to output to a printer, then use LPT1 or LPT2 (whichever is appropriate) as the output filename. The final parameter allows for color (/C) or blah non color (/NC) screen display at runtime. 3.0 Meta Command Intro Additionally, P-OPT offers a set of meta-commands. Meta-commands, if you are not familar with them, are intructions to an intermediate program as opposed to the final program. Here a meta-command is a way of sending an instruction to P-OPT (as opposed to PROCOMM) in the script file. In this case, the meta-commands allow you to send instructions to P-OPT as it is optimizing your source file. Other meta-commands allow you to preserve certain strings that might otherwise be stipped from the source file. 3.1 Meta-Command syntax P-OPT metacommands all begin with a PROCOMM remark character (";") and end with a colon ":" and are 8 characters. The ";" prevents the meta commands from interfering with PROCOMM, and the rest makes it easy for P-OPT to recognize the line as a meta-command The metacommands currently supported are: ;$TITLE: - The title or name of your script file ;$SUBTL: - A date or whatever tickles your fancy ;$AUTHR: - List the author of the script file ;$VERSN: - A version number if you wish ;$REMRK: - A remark to remain in target file :$PGSIZ: - Number of lines to print per page ;$PAGEF: - If output is to LPTx, send unconditional Form Feed ;$LNCNT: - Yes/No (1/0) switch for line numbers 3.2 Meta-Command usage Basically, P-OPT will not strip meta-commands from the source file, unless told to. This allows you to place your name, a subtitle, a version etc in a script file and not have P-OPT strip it from the source file. A meta-command MUST begin in column 1 of the source file or it too is stripped from the source and may as well have been a simple PROCOMM remark. Additionally, the ;$REMRK: meta-command will not be stripped even if the ;$MCMDS: switch is off. This makes it additioanlly helpful when used right. Right: +---------------------------- |;$REMRK: Be careful not to change S6 !! |ASSIGN S6="foo-bar" Wrong: +-------------------------------------- |ASSIGN S6="foo-bar" ;$REMRK: Be careful not to change S6 !! Additionally, the ;$REMRK: meta-command will not be stripped even if the ;$MCMDS: switch is off. This makes it additioanlly helpful when used right. 3.3 Printing with Meta-Commands If you are outputting to a printer via P-OPT, the last 4 meta-commands allow additional printer control: the first two control page length and compressed or normal type. If you have an intricate routine or subroutine going, you can force a formfeed at a specific point that makes sence to you with ;$PAGEF:. In so doing, the line counter internal to P-OPT will reset to 0. This means that the next formfeed will be however many lines later that you have $PGSIZ: set to. Finally, P-OPT will place the author, title, subtitle and version meta- command assignment at the top of each page, as well as a page number. For this reason, if you attempt to make multiple $SUBTL: assignments, only the last one would be printed. Eg: Command file: Printed output: ;$TITLE: My command file My Command File ;$AUTHR: Gizmo Mike Gizmo Mike ;$VERSN: Version 1.01 Version: 1.01 ;$SUBTL: A fine program I wrote today ;$SUBTL: I wrote today This is not a glitch but a compromise made for speed, but adds an additional benefit explained later. 3.3.5 Printer meta-command placement The 3 printer meta-commands, if used, should be placed in the very beginning of the source file after $AUTHR:, $TITLE:, $VERSN: and $SUBTL; If none of the printer meta-commands appear in the first fifteen lines of the source, the defaults are used and suprious results may occur. Printer meta-commands are ignored and stripped when outputting to disk. 3.4 Disk File output Of cource you will not always output to a printer. If output is to a disk file, the printer related meta-commands are ignored, but they still remain in the target file. However, the others will come in handy. In the top portion of the source you can put a copyright notice, a version etc and they will 'survive' P-OPT to remain in the target file. As with the print mode, only the last meta-command assignment is retained. If you are outputting to a disk file, you may find the $REMRK very handy. It simply marks a line as a "super-remark" that will survive the P-OPT process to also appear in the target file. 3.6 Meta - Command Caution Meta-commands are a very powerful feature of P-OPT, and should be used with discretion. Using too many $REMRK 's will make the output file larger and wordier than necessary, defeating the purpose of P-OPT. In fact the only meta-cpmmand that should be used more than once is $REMRK:, $SUBTL: and possibly $PAGEF: if you are outputting to printer. The others should be assigned once. 4.0 Outputting a source/output cross reference Whether you are outputting to the printer or a disk file, you can tell P-OPT to produce a cross reference of your script command file by setting $LNCNT: to a positive number in the source. When cross referencing, a fully optimized file is output with the addition of line numbers. The SOURCE line, NOT target line. This means that numbers will NOT be sequential, since simple remarks and blank lines are removed. But this allows you to reference the target file against a commented source file at run time. While, this is fully optimized, the commented line numbers will slow it down, but as a debugging aid in large script files, this should be very useful. Sample cross reference output: GOTO PRGM_END ;Src Line #: 69 ENDC ;Src Line #: 70 ENDS ;Src Line #: 71 BEGIN: ;Src Line #: 85 SET CR_I CR ;Src Line #: 86 SET PARI EVEN ;Src Line #: 87 Though not tested, in theory, later in the file, you could toggle off the line numbers with a "$LNCNT:0" meta-command. 5.0 External Data file All that P-OPT needs to know to run is read from the command line, but in the interest of flexibility, it reads the translation for long to short form of PROCOMM command words from an external file called (and hard coded as such) PROCMDS.LST. This is created with a standard ASCII text editor in the format of: LONGNAME,LNAM with the long, formal name on the left, the abbreviated form on the right, separated by a comma. Note that the PROCMDS.LST you should have recieved with P-OPT.EXE may or may not be a complete list of PROCOMM command words! Look thru it compared to the PROCOMM docs and edit as you need. DO NOT ADD ANY COMMANDS THAT ARE UNDER 5 CHARACTERS LONG! Adding words like RGET and SEND or FIND to the list is pointless, first because they do not have a shorter abbreviation, second P-OPT ignores anything under 4 characters long, third adding them just for the sake of adding them will cause P-OPT to require more memory, and it will take it longer to search the larger array of command words. In utilizing an external data file, the programming was done "blind". That is, P-OPT works by a set of rules rather than acting in response to specific words. This means that only if (when?) the PROCOMM script language changes would you outgrow P-OPT. Also in using an external text file, some added features are available and explained later. 6.0 Advanced features Most of the best parts of P-OPT will never be seen by you.: Since there are some BBS out there that still require a semi colon top stack commands, P-OPT will check to see if a line with a ";" in it is inside a quote and if so, leave it alone. However, if an additional remark trails a quoted semi colon, it will be stripped whether in a quote or not. In scooting quoted literals to the left (TRANSMIT "password" becoming TRANS"password"), P-OPT looks to see that they is a space preceeding the first quote, and if so, only then is it supposed to scoot it to the left. P-OPT is not case sensitive, either in the original source file, or the PROCOMM data command file. P-OPT will convert the source line to upper case, maul it to death, then output the result. The output will NOT be converted to upper case however. The output will be the literal from the source file AND from the PROCMDS.LST data file. If you use lower case in the data file, and some upper in the source file, P-OPT will (in spite of you) make a match and replace it successfuilly, but the target (output) file will be in mixed case. Most all of PROCOMM's command key words are the first command on a line, the obvious exceptions of SET and IF. In the interest of speed, P-OPT first looks for a meta-command, then strips blanks and then looks at the first word for optimization. If that word is "SET" or "IF" then it shifts to the next word to optimize. If the first is "IF" and the second is "NOT" then it shifts to the third word. In all cases nothing right of a quote is optimized, so that if you are RGETing of FINDing something, it will look for what ever you have quoted. Note: If you have a specific application that leaves unoptimized command words in the optimized (output) line, I would like to know about it and see an example or two, as this algorithm is not etched in stone, but it is just about as quick as I can make it. 6.1 Advanced meta-command usage When used with the printer as an output, whatever your source file has assigned to $AUTHR:, $TITLE: and $SUBTL: as well as $VERSN: will be printed at the top of each page along with a page number. As noted, meta-commands can be reassigned throughout the command file. This means that for print formatting, aside from just inserting the $PAGEF: meta-command to force a form feed, you could also PRIOR to the form feed, reassign $SUBTL: meta-command to assign a separate subtitle for each page holding a specfic routine. Irregardless of their placement in the source file, P-OPT should read and act on all meta commands as encountered, as long as they start in column one. The reason for needing to declare them in the first 10 lines of the source for starters, is so that BEFORE P-OPT goes to output the first few lines, it needs to know things like $LNCNT: and $PGSIZ: and so forth. To accomplish this, P-OPT "pre-reads" the first few (10) lines to get these parameters, then it starts over to actually optimize the file. After that, meta-command parameters can be changed on the fly to allow you to go so far as to print easch routine on a separate page ($PAGEF:) and even $SUBTL: each page with a different name. Finally, the new QMODEM 3.0 just came out, with a greatly enhanced script language, and it appears that you could edit the PROCMDS.LST to allow some possible translations from PROCOMM to QMODEM. That is, PROCOMM uses TRANSMIT to signal the system to send a literal or a string, QMODEM uses SEND. In your PROCMDS.LST you could edit a copy to read: TRANSMIT,SEND Converting back from QMODEM to PROCOMM probably will not work because most of QMODEM's words seem to be 4 chars long or less already. eg SEND,TRANS would not work because "SEND" would be ignored being under 5 chars long. Additionally, aside from not knowing if QMODEM even recognizes shorter versions of the key words, it looks like P-OPT's meta-commands might choke Qmodem or vice versa since they both use the "$word" format. 7.0 Future Releases One of the most powerful and features of P-OPT are it's meta-commands. I toyed with one for printer codes, but they are too variable and it is easier for you to set it into conpressed print, or whatever than me, given the variety of printers. However, if you have a suggestion for additional meta-commands, call my board and leave a note, and we will look into it. I do plan a relase soon with enhanced titling especially in the print mode, but as an optimizer per se it seems to work very well. I also think I can triomn a few seconds here and there if I tried real hard. 8.0 Acknowledgements QMDOEM is Copyright John Friel PROCOMM is Copyright DATASTORM VERSA is Copyright Allen Brunson P-OPT is Copyright InfoSoft, 1987, ALL RIGHTS RESERVED P-OPT is Copyrighted, but no "donations" or "contributions" are solicited for it, nor is the source code available for sal P-OPT may not be sold, even for nominal (or otherwise) so-called disk fee, nor may it be included in any library, collection. It may not be offered for a donation or for monetary remuneration of any sort or included in a collection of programs by any organization either for-profit or non-profit. P-OPT must also be distributed with this documention in uneditted form. Special Thanks to Allen Brunson, without who's need for something to optimize VERSA, P-OPT would never have been conceived. P-OPT is written in QuickBASIC 2.01 All routines used in P-OPT were written by me or are from my own library of routines except for EXIST (to check if a file exists). 9.0 History April 28, 1987 - Released Version 1.0